home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / tcl / extend / man / Handles.3 < prev    next >
Encoding:
Text File  |  1993-10-26  |  5.6 KB  |  209 lines  |  [TEXT/MPS ]
  1. .\"
  2. .\" Handles.man
  3. .\"
  4. .\" Extended Tcl binary file search command.
  5. .\"----------------------------------------------------------------------------
  6. .\" Copyright 1992-1993 Karl Lehenbauer and Mark Diekhans.
  7. .\"
  8. .\" Permission to use, copy, modify, and distribute this software and its
  9. .\" documentation for any purpose and without fee is hereby granted, provided
  10. .\" that the above copyright notice appear in all copies.  Karl Lehenbauer and
  11. .\" Mark Diekhans make no representations about the suitability of this
  12. .\" software for any purpose.  It is provided "as is" without express or
  13. .\" implied warranty.
  14. .\"----------------------------------------------------------------------------
  15. .\" $Id: Handles.3,v 2.2 1993/07/20 08:35:45 markd Exp $
  16. .\"----------------------------------------------------------------------------
  17. .\"
  18. .TH Handles TCL "" "Tcl"
  19. .ad b
  20. .BS
  21. .SH NAME
  22. Tcl_HandleAlloc, Tcl_HandleFree, Tcl_HandleTblInit, Tcl_HandleTblRelease, Tcl_HandleTblUseCount Tcl_HandleWalk, Tcl_HandleXlate \- Dynamic, handle addressable tables.
  23.  
  24. .SH SYNOPSIS
  25. .PP
  26. .nf
  27. .ft CW
  28. #include <tclExtend.h>
  29.  
  30. void_pt
  31. Tcl_HandleTblInit (const char *handleBase,
  32.                    int         entrySize,
  33.                    int         initEntries);
  34.  
  35. int
  36. Tcl_HandleTblUseCount (void_pt  headerPtr,
  37.                        int      amount);
  38.  
  39. void
  40. Tcl_HandleTblRelease (void_pt headerPtr);
  41.  
  42. void_pt
  43. Tcl_HandleAlloc (void_pt   headerPtr,
  44.                  char     *handlePtr);
  45.  
  46. void_pt
  47. Tcl_HandleXlate (Tcl_Interp *interp,
  48.                  void_pt     headerPtr,
  49.                  const char *handle);
  50.  
  51. void_pt
  52. Tcl_HandleWalk (void_pt   headerPtr,
  53.                 int      *walkKeyPtr);
  54.  
  55. void
  56. Tcl_WalkKeyToHandle (void_pt   headerPtr,
  57.                      int       walkKey,
  58.                      char     *handlePtr);
  59.  
  60. void
  61. Tcl_HandleFree (void_pt headerPtr,
  62.                 void_pt entryPtr);
  63. .ft R
  64. .fi
  65. '
  66. .SH DESCRIPTION
  67. .PP
  68. The Tcl handle facility provides a way to manage table entries that may be
  69. referenced by a textual handle from Tcl code.  This is provided for 
  70. applications that need to create data structures in one command, return a
  71. reference (i.e. pointer) to that particular data structure and then access
  72. that data structure in other commands. An example application is file handles.
  73. .PP
  74. A handle consists of a base name, which is some unique, meaningful name, such
  75. as `\fBfile\fR' and a numeric value appended to the base name (e.g. `file3').
  76. The handle facility is designed to provide a standard mechanism for building
  77. Tcl commands that allocate and access table entries based on an entry index.
  78. The tables are expanded when needed, consequently pointers to entries should
  79. not be kept, as they will become invalid when the table is expanded.  If the
  80. table entries are large or pointers must be kept to the entries, then the
  81. the entries should be allocated separately and pointers kept in the handle 
  82. table.  A use count is kept on the table.  This use count is intended to
  83. determine when a table shared by multiple commands is to be release.
  84. '
  85. .SS Tcl_HandleTblInit
  86. Create and initialize a Tcl dynamic handle table.  The use count on the
  87. table is set to one.
  88. .PP
  89. Parameters:
  90. .RS 2
  91. \fBo \fIhandleBase\fR - The base name of the handle, the handle will be
  92. returned in the form "baseNN", where NN is the table entry number.
  93. .br
  94. \fBo \fIentrySize\fR - The size of an entry, in bytes.
  95. .br
  96. \fBo \fIinitEntries\fR - Initial size of the table, in entries.
  97. .RE
  98. .PP
  99. Returns:
  100. .RS 2
  101. A pointer to the table header.  
  102. .RE
  103. '
  104. .SS Tcl_HandleTblUseCount
  105. .PP
  106. Alter the handle table use count by the specified amount, which can be
  107. positive or negative.  Amount may be zero to retrieve the use count.
  108. .PP
  109. Parameters:
  110. .RS 2
  111. \fBo \fIheaderPtr\fR - Pointer to the table header.
  112. .br
  113. \fBo \fIamount\fR - The amount to alter the use count by.
  114. .RE
  115. .PP
  116. Returns:
  117. .RS 2
  118. The resulting use count.
  119. .RE
  120. '
  121. .SS Tcl_HandleTblRelease
  122. .PP
  123. Decrement the use count on a Tcl dynamic handle table.  If the count
  124. goes to zero or negative, then release the table.
  125. .PP
  126. Parameters:
  127. .RS 2
  128. \fBo \fIheaderPtr\fR - Pointer to the table header.
  129. .RE
  130. '
  131. .SS Tcl_HandleAlloc
  132. .PP
  133. Allocate an entry and associate a handle with it.
  134. .PP
  135. Parameters:
  136. .RS 2
  137. \fBo \fIheaderPtr\fR - A pointer to the table header.
  138. .br
  139. \fBo \fIhandlePtr\fR - Buffer to return handle in. It must be big enough to
  140. hold the name.
  141. .RE
  142. .PP
  143. Returns:
  144. .RS 2
  145. A pointer to the allocated entry (user part).
  146. .RE
  147. '
  148. .SS Tcl_HandleXlate
  149. .PP
  150. Translate a handle to a entry pointer.
  151. .PP
  152. Parameters:
  153. .RS 2
  154. \fBo \fIinterp\fR - A error message may be returned in result.
  155. .br
  156. \fBo \fIheaderPtr\fR - A pointer to the table header.
  157. .sp
  158. o \fIhandle\fR - The handle assigned to the entry.
  159. .RE
  160. .PP
  161. Returns:
  162. .RS 2
  163. A pointer to the entry, or NULL if an error occured.
  164. .RE
  165. '
  166. .SS Tcl_HandleWalk
  167. .PP
  168. Walk through and find every allocated entry in a table.  Entries may
  169. be deallocated during a walk, but should not be allocated.
  170. .PP
  171. Parameters:
  172. .RS 2
  173. \fBo \fIheaderPtr\fR - A pointer to the table header.
  174. .br
  175. \fBo \fIwalkKeyPtr\fR - Pointer to a variable to use to keep track of the
  176. place in the table.  The variable should be initialized to -1 before
  177. the first call.
  178. .RE
  179. Returns:
  180. .RS 2
  181. A pointer to the next allocated entry, or NULL if there are not more.
  182. .RE
  183. '
  184. .SS Tcl_WalkKeyToHandle
  185. .PP
  186. Convert a walk key, as returned from a call to Tcl_HandleWalk into a
  187. handle.  The Tcl_HandleWalk must have succeeded.
  188. .PP
  189. Parameters:
  190. .RS 2
  191. \fBo \fIheaderPtr\fR - A pointer to the table header.
  192. .br
  193. \fBo \fIwalkKey\fR - The walk key.
  194. .br
  195. \fBo \fIhandlePtr\fR - Buffer to return handle in. It must be big enough to
  196. hold the name.
  197. .RE
  198. '
  199. .SS Tcl_HandleFree
  200. .PP
  201. Frees a handle table entry.
  202. .PP
  203. Parameters:
  204. .RS 2
  205. \fBo \fIheaderPtr\fR - A pointer to the table header.
  206. .br
  207. \fBo \fIentryPtr\fR - Entry to free.
  208. .RE
  209.